OpenEdge Development:<br />Progress 4GL Reference OVERLAY statement

Overlays a character expression in a field or variable starting at a given position, and optionally for a given length.

Syntax


OVERLAY ( `target` , `position` [ , `length` [ , `type` ] ] ) = `expression`

The name of the character field or variable that you want to overlay an expression.

An integer expression that indicates the first character position in target where you want to store expression. The value of position must be positive. If position is longer than target, Progress pads target with blanks to match position.

An integer expression that indicates the number of positions you want to allocate for the storage of expression. The expression is truncated or padded with blanks to match length. If you do not use the length argument or specify -1 as the length, OVERLAY uses the entire expression.

A character expression that directs Progress to interpret the specified position and length values as character units, bytes, or columns. A double-byte character registers as one character unit. By default, Progress interprets the specified position and length values as character units.

There are three valid types: "CHARACTER," "RAW," and "COLUMN." The expression "CHARACTER" specifies character units. The expression "RAW" specifies bytes. The expression "COLUMN" specifies display or print character-columns. If you specify the type as a constant expression, Progress validates the type specification at compile time. If you specify the type as a non-constant expression, Progress validates the type specification at run time.

An expression that results in an integer value, constant, field name, variable name, or expression that results in a character string that you want to overlay on target. If you specify length, the expression is truncated or padded with blanks to match length.

The r-replc1.p procedure lets you search for, and replace text strings in a paragraph in a window. When you run the procedure, you see the paragraph, which is an array with an extent of five. You also see a prompt. Enter the text string you want the system to search for, and the new text you want in its place. The procedure searches the paragraph, one line at a time, for the text you entered. The procedure uses the OVERLAY statement to replace the string of old text with the string of new text. The procedure also determines the length of the old text and the new text.

r-replc1.p
DEFINE VARIABLE chktext AS CHARACTER. DEFINE VARIABLE i AS INTEGER. DEFINE VARIABLE chkndx AS INTEGER. DEFINE VARIABLE ndx AS INTEGER. DEFINE VARIABLE old-text AS CHARACTER. DEFINE VARIABLE new-text AS CHARACTER. DEFINE VARIABLE max-len AS INTEGER. DEFINE VARIABLE comment AS CHARACTER FORMAT "x(49)" EXTENT 5 INITIAL ["You are probably interested in PROGRESS because", "you have a lot of information to organize. You", "want to get at the information, add to it, and", "change it, without a lot of work and aggravation.", "You made the right choice with PROGRESS." ]. DISPLAY comment WITH CENTERED FRAME comm NO-LABELS TITLE "Why You Chose PROGRESS" ROW 4. REPEAT: SET old-text LABEL "Enter text to search for" new-text LABEL "Enter text to replace with" WITH FRAME replace SIDE-LABELS CENTERED. max-len = MAXIMUM(LENGTH(old-text), LENGTH(new-text)). DO i = 1 TO 5: ndx = 1. DO ndx = 1 TO LENGTH(comment[i]): chktext = SUBSTRING(comment[i], ndx). chkndx = INDEX(chktext, old-text). IF chkndx <> 0 THEN DO: ndx = ndx + chkndx - 1. OVERLAY(comment[i], ndx, max-len, "CHARACTER") = new-text. ndx = max-len. END. END. DISPLAY comment[i] WITH FRAME comm. END. END.

r-replc1.p

DEFINE VARIABLE chktext  AS CHARACTER.
DEFINE VARIABLE i        AS INTEGER.
DEFINE VARIABLE chkndx   AS INTEGER.
DEFINE VARIABLE ndx      AS INTEGER.
DEFINE VARIABLE old-text AS CHARACTER.
DEFINE VARIABLE new-text AS CHARACTER.
DEFINE VARIABLE max-len  AS INTEGER.
DEFINE VARIABLE comment  AS CHARACTER FORMAT "x(49)" EXTENT 5
  INITIAL ["You are probably interested in PROGRESS because",
    "you have a lot of information to organize.  You",
    "want to get at the information, add to it, and",
    "change it, without a lot of work and aggravation.",
    "You made the right choice with PROGRESS." ].

DISPLAY comment WITH CENTERED FRAME comm NO-LABELS
  TITLE "Why You Chose PROGRESS" ROW 4.

REPEAT:
    SET old-text LABEL "Enter text to search for"
    new-text LABEL "Enter text to replace with"
      WITH FRAME replace SIDE-LABELS CENTERED.
  max-len = MAXIMUM(LENGTH(old-text), LENGTH(new-text)).
  DO i = 1 TO 5:
    ndx = 1.
    DO ndx = 1 TO LENGTH(comment[i]):
      chktext = SUBSTRING(comment[i], ndx).
      chkndx = INDEX(chktext, old-text).
      IF chkndx <> 0 THEN DO:
        ndx = ndx + chkndx - 1.
        OVERLAY(comment[i], ndx, max-len, "CHARACTER") = new-text.
        ndx = max-len.
      END.
    END.
    DISPLAY comment[i] WITH FRAME comm.
  END.
END.

Notes

The OVERLAY statement is not equivalent to the SUBSTRING statement. When you use the OVERLAY statement, a specified number of byte or character units within the target string are overlaid with the same number of units from an expression. Therefore, the length of the target string does not change. The SUBSTRING statement replaces a specified number of units within the target string with the entire value of an expression. This may change the length of the target string.

Do not split double-byte characters. This statement allows you to overlay either the lead or trail-byte of the target string when you specify "RAW" as the type parameter.

OVERLAY statement

Syntax

Notes

See also